Inside Macintosh: More Macintosh Toolbox
The Component Manager provides a number of routines that help your component manage the connections it maintains with its client applications and components.
Use the SetComponentInstanceStorage procedure to inform the Component Manager of the memory your component is using to maintain global data for a connection. Whenever the client application issues a request to the connection, the Component Manager provides to your component the handle to the allocated memory for that connection along with the parameters for the request. You can also use the GetComponentInstanceStorage function to retrieve a handle to the storage for a connection.
Use the CountComponentInstances function to count all the connections that are currently maintained by your component. This routine is similar to the CountComponents routine that the Component Manager provides to client applications and components.
Use the SetComponentInstanceA5 procedure to set the A5 world for a connection. Once you set the A5 world for a connection, the Component Manager automatically switches the contents of the A5 register when your component receives a request for that connection. When your component returns to the Component Manager, the Component Manager restores the A5 register. Your component can use the GetComponentInstanceA5 function to retrieve the A5 world for a connection.
When an application or component opens a connection to your component, the Component Manager sends your component an open request. In response to this open request, your component should set up an environment to service the connection. Typically, your component should allocate some memory for the connection. Your component can then use that memory to maintain state information appropriate to the connection.
The SetComponentInstanceStorage procedure allows your component to pass a handle to this memory to the Component Manager. The Component Manager then provides this handle to your component each time the client application requests service from this connection.
PROCEDURE SetComponentInstanceStorage
(aComponentInstance: ComponentInstance; theStorage: Handle);
The SetComponentInstanceStorage procedure associates the handle passed in the parameter theStorage with the connection specified by the aComponentInstance parameter. Your component should dispose of any allocated memory for the connection only in response to the close request.
Note that whenever an open request fails, the Component Manager always issues the close request. Furthermore, the value stored with SetComponentInstanceStorage is always passed to the close request, so it must be valid or NIL . If the open request tries to dispose of its allocated memory before returning, it should call SetComponentInstanceStorage again with a NIL handle to keep the Component Manager from passing an invalid handle to the close request.
For an example that allocates memory in response to an open request, see Listing 6 .
The GetComponentInstanceStorage function allows your component to retrieve a handle to the memory associated with a connection. Your component tells the Component Manager about this memory by calling the SetComponentInstanceStorage procedure. Typically, your component does not need to use this function, because the Component Manager provides this handle to your component each time the client application requests service from this connection.
FUNCTION GetComponentInstanceStorage
(aComponentInstance: ComponentInstance): Handle;
The CountComponentInstances function allows you to determine the number of open connections being managed by a specified component. This function can be useful if you want to restrict the number of connections for your component or if your component needs to perform special processing based on the number of open connections.
FUNCTION CountComponentInstances (aComponent: Component): LongInt;
The SetComponentInstanceA5 procedure allows your component to set the A5 world for a connection.
PROCEDURE SetComponentInstanceA5
(aComponentInstance: ComponentInstance; theA5: LongInt);
The SetComponentInstanceA5 procedure sets the A5 world for the specified component instance. Once you set the A5 world for a connection, the Component Manager automatically switches the contents of the A5 register when your component receives a request over that connection. When your component returns to the Component Manager, the Component Manager restores your client's A5 value.
If your component has been registered globally and you have not set an A5 value, the A5 register is set to 0. In this case you should set the A5 world of your component instance to your client's A5 value by using SetComponentInstanceA5 .
In general, your component uses this procedure only if it is registered globally; in this case, it typically calls SetComponentInstanceA5 when processing the open request for a new connection.
You can use the GetComponentInstanceA5 function to retrieve the value of the A5 register for a specified connection. Your component sets the A5 register by calling the SetComponentInstanceA5 function, as previously described. The Component Manager then sets the A5 register for your component each time the client requests service on this connection. If your component has been registered globally and you have not set an A5 value, the A5 register is set to 0. In this case you should use your client's A5 value.
FUNCTION GetComponentInstanceA5
(aComponentInstance: ComponentInstance): LongInt;